#ifndef __SW_TIMER_H__
#define __SW_TIMER_H__

#include <stdint.h>
#include <stdbool.h>
#include <stdlib.h>

/**
 * 定时器状态枚举
 * 描述软件定时器的当前运行状态
 */
typedef enum {
    SW_TIMER_STOPPED = 0,  // 停止状态：未运行，不在定时链表中
    SW_TIMER_RUNNING,      // 运行状态：正在计时，已加入定时链表
    SW_TIMER_DELAYED       // 延迟状态：仅用于单次定时未触发时（预留扩展）
} sw_timer_state_t;

/**
 * 定时器模式枚举
 * 描述软件定时器的触发方式
 */
typedef enum {
    SW_TIMER_ONE_SHOT = 0, // 单次触发：定时时间到后执行一次回调，自动停止
    SW_TIMER_PERIODIC      // 周期性触发：定时时间到后执行回调，重新开始计时
} sw_timer_mode_t;

/**
 * 软件定时器结构体
 * 每个定时器实例的核心数据，用户无需直接修改成员
 */
typedef struct sw_timer {
    struct sw_timer* next;          // 链表节点：用于将多个定时器串联成链表
    uint32_t timeout_ticks;         // 总定时 ticks：用户设置的定时时间（单位：ticks）
    uint32_t remaining_ticks;       // 剩余 ticks：当前剩余的计时 ticks（递减至0触发）
    sw_timer_mode_t mode;           // 定时器模式：单次/周期
    sw_timer_state_t state;         // 定时器状态：运行/停止
    void (*timeout_func)(void*);    // 超时回调函数：定时结束后执行的函数
    void* user_data;                // 用户数据：传递给回调函数的参数
} sw_timer_t;

/**
 * 初始化软件定时器模块
 * @param tick_freq 硬件定时器的触发频率（单位：Hz），即每秒产生多少个ticks
 *                  例如：1ms触发一次则为1000Hz，1个tick = 1ms
 */
void sw_timer_init(uint32_t tick_freq);

/**
 * 创建软件定时器实例
 * @param mode 定时器模式（单次/周期）
 * @param timeout_func 超时回调函数（定时结束后执行）
 * @param user_data 传递给回调函数的用户数据（可为NULL）
 * @return 成功返回定时器指针，失败返回NULL（内存不足或参数无效）
 */
sw_timer_t* sw_timer_create(sw_timer_mode_t mode, 
                           void (*timeout_func)(void*), 
                           void* user_data);

/**
 * 启动软件定时器
 * @param timer 要启动的定时器（由sw_timer_create创建）
 * @param timeout_ms 定时时间（单位：毫秒）
 * @return 成功返回true，失败返回false（参数无效或未初始化）
 */
bool sw_timer_start(sw_timer_t* timer, uint32_t timeout_ms);

/**
 * 停止软件定时器
 * @param timer 要停止的定时器
 * 说明：停止后定时器从链表中移除，状态改为SW_TIMER_STOPPED
 */
void sw_timer_stop(sw_timer_t* timer);

/**
 * 删除软件定时器
 * @param timer 要删除的定时器
 * 说明：先停止定时器并从链表移除，再释放内存
 */
void sw_timer_delete(sw_timer_t* timer);

/**
 * 软件定时器心跳函数
 * 必须由硬件定时器周期性调用（每次硬件中断时调用）
 * 功能：递减所有运行中定时器的剩余ticks，检查是否超时并执行回调
 */
void sw_timer_tick(void);

#endif